lib/repo: Define a metadata key, ostree.deploy-collection-id

This commit defines a metadata key that tells clients to update their
remote config to add a collection ID. This functionality is currently
implemented in Flatpak for the key "xa.collection-id", but there are two
good reasons for moving the key to OSTree:

1) Servers such as Flathub shouldn't set xa.collection-id in their
metadata now or in the medium term future, because many users are still
using old versions of Flatpak and OSTree[1] which would hit various
bugs[2][3][4] on the P2P code paths that are enabled by collection IDs.
Defining a new key means that only clients running recent
(as-yet-unreleased) versions of Flatpak and OSTree will pay attention to
it and deploy the collection ID, leaving the users on old versions
unaffected.

2) OSTree is as "invested" in collection IDs as Flatpak, so there's no
reason the key should be defined in Flatpak rather than here. According
to Philip Withnall, the reason the key was put in Flatpak originally was
that at the time there was uncertainty about tying OSTree to collection
IDs.

[1] https://ahayzen.com/direct/flathub.html#downloadsbyflatpakstacked
[2] https://github.com/ostreedev/ostree/commit/e4e6d85ea
[3] https://github.com/flatpak/flatpak/commit/5813639f
[4] https://github.com/flatpak/flatpak/commit/5b21a5b7

Closes: #1726
Approved by: pwithnall

diff --git a/apidoc/ostree-sections.txt b/apidoc/ostree-sections.txt
index 0ec1cfd3bd5d59922dd56ea98eeefe6526f30392..440fe0c35a6af167a0a12d4a1f293f046b054ad2 100644 (file)
--- a/apidoc/ostree-sections.txt
+++ b/apidoc/ostree-sections.txt
@@ -598,6 +598,7 @@ ostree_repo_pull_from_remotes_async
 ostree_repo_pull_from_remotes_finish
 ostree_repo_resolve_keyring_for_collection
 OSTREE_REPO_METADATA_REF
+OSTREE_META_KEY_DEPLOY_COLLECTION_ID
 </SECTION>
 
 <SECTION>

diff --git a/src/libostree/ostree-repo.h b/src/libostree/ostree-repo.h
index 11b7927e7a773209a8bdede0388b9de42ebe9c55..6159fc244eb5d0c7f721481d17b6980976f3d536 100644 (file)
--- a/src/libostree/ostree-repo.h
+++ b/src/libostree/ostree-repo.h
@@ -1397,6 +1397,29 @@ gboolean ostree_repo_regenerate_summary (OstreeRepo     *self,
  */
 #define OSTREE_REPO_METADATA_REF "ostree-metadata"
 
+/**
+ * OSTREE_META_KEY_DEPLOY_COLLECTION_ID:
+ *
+ * GVariant type `s`. This key can be used in the repo metadata which is stored
+ * in OSTREE_REPO_METADATA_REF as well as in the summary. The semantics of this
+ * are that the remote repository wants clients to update their remote config
+ * to add this collection ID (clients can't do P2P operations involving a
+ * remote without a collection ID configured on it, even if one is configured
+ * on the server side). Clients must never change or remove a collection ID
+ * already set in their remote config.
+ *
+ * Currently, OSTree does not implement changing a remote config based on this
+ * key, but it may do so in a later release, and until then clients such as
+ * Flatpak may implement it.
+ *
+ * This is a replacement for the similar metadata key implemented by flatpak,
+ * `xa.collection-id`, which is now deprecated as clients which supported it had
+ * bugs with their P2P implementations.
+ *
+ * Since: 2018.9
+ */
+#define OSTREE_META_KEY_DEPLOY_COLLECTION_ID "ostree.deploy-collection-id"
+
 G_END_DECLS